.\" man(7) manpage by rosenkra@hall.cray.com (Bill Rosenkranz)
.\" Modified a bit for MINIX 3 by Kees J. Bot (kjb@cs.vu.nl)
.\"
.TH MAN 7
.SH NAME
man - macros for use in manual pages
.SH SYNOPSIS
.B man
.I file
.I [section]
.SH DESCRIPTION
These macros are used to lay out reference pages for manuals. The
.BR man (1)
program internally implements these macros, as
.B nroff
is not present.
.PP
Any text argument
.I t
may be zero to six words.  Quotes may be used to include blanks in a 'word'.
.I T
can be empty, in which case the next line is used.
.PP
A prevailing indent distance is remembered between successive
indented paragraphs, and is reset to default value upon
reaching a non-indented paragraph (i.e. at .SH or .SS).
.SH "REQUEST SUMMARY"
.nf
Request	  Cause   Explanation
          Break?
.fi
.sp
.TP 20
.BR ".TH n s c v d\ " yes
Begin page named 
.B n
of chapter
.BR s ;
.B c
is the chapter name;
.B d
is the date of the most recent change;
.B v
is version number.
Sets prevailing indent and tabs to default.
.TP 20
.BR ".SH t       \ " yes
Subhead. Quote to embed blanks.
.TP 20
.BR ".SS t       \ " yes
Subsection. Quote to embed blanks. No indent for t.
.TP 20
.BR ".PP          \ " yes
Begin paragraph.
Set prevailing indent to default.
.TP 20
.BR ".HP x       \ " yes
Begin paragraph with hanging indent.
Set prevailing indent to
.BR x .
.TP 20
.BR ".TP x       \ " yes
Begin indented paragraph with hanging tag given by next line.
Set prevailing indent to
.BR x .
.TP 20
.BR ".IP t x   \ " yes
Same as
.B .TP t
with tag
.BR t .
Often used to get an indented paragraph without a tag.
Set prevailing indent to
.BR x .
.TP 20
.BR ".RS          \ " yes
Start relative indent, move left margin in distance 5.
.TP 20
.BR ".RE          \ " yes
End of relative indent.
Set prevailing indent to amount of starting .RS.
.TP 20
.BR ".nf          \ " yes
Turn line fill off.
.TP 20
.BR ".fi          \ " yes
Turn line fill on.
.TP 20
.BR ".na          \ " no
Leave right margin unaligned.
.TP 20
.BR ".ad          \ " no
Line up right margin.
.TP 20
.BR ".B t         \ " no
Text t is bold. Quote to embed blanks.
.TP 20
.BR ".I t         \ " no
Text t is italic. Quote to embed blanks.
.TP 20
.BR ".BI t       \ " no
Text alternates bold followed by italic. Quote to embed blanks.
.TP 20
.BR ".BR t       \ " no
Text alternates bold followed by roman. Quote to embed blanks.
.TP 20
.BR ".IR t       \ " no
Text alternates italic followed by roman. Quote to embed blanks.
.SH EXAMPLE
The following illustrates some of the requests available
using these macros:
.RS
.nf
\&.\\" this is a comment
\&.TH DEMO 1
\&.SH NAME
demo \\- show how to use \e-man package
\&.SH SYNOPSIS
\&.B demo
\&.RI [ options ]
\&.IR file " ..."
\&.SH DESCRIPTION
This is a test for showing how to use the
\&.BR man (1)
command. It shows how to use .TH, .SH, .PP, .B, .I, and .IP
commands.
\&.PP
This will be a new paragraph. You can also use normal
\&.BR nroff (1)
commands in the text.
\&.SS Man Commands
\&.IP '\\"'
This is the comment command.  \e" You won't see this.
\&.IP nf
No fill mode (the normal mode is fill mode where things
get justified right and left).
\&.IP fi
Re-enter fill mode.
\&.IP br
Break line here no matter what.
\&.IP sp
Vertical space (also causes a break to occur).
\&.sp
Note that to continue an indent and make a new paragraph (as
is the case here), just put in a space (.sp).
\&.PP
Now we should be at a new paragraph.
.fi
.RE
.PP
Executing
.B man ./demo.1
results in the following output:  (Ignoring page headers and footers)
.PP
.RS
.B NAME
.RS
demo \- show how to use \-man package
.RE
.sp
.B SYNOPSIS
.RS
.B demo
.RI [ options ]
.IR file " ..."
.RE
.sp
.B DESCRIPTION
.RS
This is a test for showing how to use the
.BR man (1)
command. It shows how to use .TH, .SH, .PP, .B, .I, and .IP
commands.
.sp
This will be a new paragraph. You can also use normal
.BR man (1)
macros in the text.
.RE
.sp
.B Man Commands
.RS
.RS
.sp
\&'\\"'	This is the comment command.
.sp
nf	No fill mode (the normal mode is fill mode where things
get justified right and left).
.sp
fi	Re-enter fill mode.
.sp
br	Break line here no matter what.
.sp
sp	Vertical space (also causes a break to occur).
.sp
Note that to continue an indent and make a new paragraph (as
is the case here), just put in a space (.sp).
.RE
.sp
Now we should be at a new paragraph.
.RE
.RE
.SH CONVENTIONS
A typical manual page for a command or function is laid out as follows:
.nf

     .TH TITLE [1-8]
          The name of the command or function in upper-case,
          which serves as the title of the manual page. This is
          followed by the number of the section in which it
          appears.

     .SH NAME
          name - one-line summary

          The name, or list of names, by which the command is
          called, followed by a dash and then a one-line summary
          of the action performed.  All in roman font, this sec-
          tion contains no troff(1) commands or escapes, and no
          macro requests.  It is used to generate the whatis(1)
          database.

     .SH SYNOPSIS

          Commands:

               The syntax of the command and its arguments as
               typed on the command line.  When in boldface, a
               word must be typed exactly as printed.  When in
               italics, a word can be replaced with text that you
               supply.  Syntactic symbols appear in roman face:

               [ ]  An argument, when surrounded by brackets is
                    optional.

               |    Arguments separated by a vertical bar are
                    exclusive.  You can supply only item from
                    such a list.

               ...  Arguments followed by an elipsis can be
                    repeated.  When an elipsis follows a brack-
                    eted set, the expression within the brackets
                    can be repeated.

          Functions:

               If required, the data declaration, or #include
               directive, is shown first, followed by the  func-
               tion declaration. Otherwise, the function declara-
               tion is shown.

     .SH DESCRIPTION
          A narrative description of the command or function in
          detail, including how it interacts with files or data,
          and how it handles the standard input, standard output
          and standard error.

          Filenames, and references to commands or functions
          described elswhere in the manual, are italicised.  The
          names of options, variables and other literal terms are
          in boldface.

     .SH OPTIONS
          The list of options along with a description of how
          each affects the commands operation.

     .SH EXAMPLES
          Examples of how to use the command.

     .SH ENVIRONMENT
          Environment variables used.

     .SH DIAGNOSTICS
          A list of diagnostic messages and an explanation of
          each.

     .SH FILES
          A list of files associated with the command or func-
          tion.

     .SH "SEE ALSO"
          A comma-separated list of related manual pages,
          followed by references to other published materials.
          This section contains no troff(1) escapes or commands,
          and no macro requests.

     .SH BUGS
          A description of limitations, known defects, and possi-
          ble problems associated with the command or function.

     .SH AUTHOR
          The program's author and any pertinent release info.
.fi
.SH SEE ALSO
.BR man (1).
